# Mutex : Mutex lock

The Mutex module provides multi-tasking mutual exclusion operations, and the protection of shared resources can be mutually exclusive using this module. The JSRE mutex lock supports priority inheritance algorithm to prevent priority inversion and to improve system real-time performance.

User can use the following code to import the Mutex module.

var Mutex = require("mutex");

# Example

• main.js

var Mutex = require("mutex");

var m = new Mutex("test");
var t = new Task("./task.js");

while (true) {
  m.lock();
  console.log("1111111");
  console.log("2222222");
  console.log("3333333");
  m.unlock();
  sys.sleep(10); // Relax CPU.
}

• task.js

var Mutex = require("mutex");

var m = new Mutex("test");

while (true) {
  m.lock();
  console.log("4444444");
  console.log("5555555");
  console.log("6666666");
  m.unlock();
  sys.sleep(10); // Relax CPU.
}

The main.js output '1111111', '2222222', '3333333' will not be preempted by the task.js output, and the task.js output '4444444', '5555555', '6666666' will not be preempted by main.js output.

The current process has a global mutex by default. If there is no special real-time requirement, you can protect the atomic operation of the shared resource as follows:

# Example

• main.js

var t = new Task("./task.js");

while (true) {
  synchronize(() => {
    console.log("1111111");
    console.log("2222222");
    console.log("3333333");
  });
  sys.sleep(10); // Relax CPU.
}

• task.js

while (true) {
  synchronize(() => {
    console.log("4444444");
    console.log("5555555");
    console.log("6666666");
  });
  sys.sleep(10); // Relax CPU.
}

synchronize is a global mutex protection mechanism and easy to use, but may lead to decrease in multitasking parallelism.

# Support

The following shows Mutex module APIs available for each permissions.

# Mutex Class

# new Mutex(name[, prioQueue[, eventBlock]])

• name {String} Mutex name.
• prioQueue {Boolean} Priority waiting queue. default: false.
• eventBlock {Boolean} Whether to block all asynchronous events between locking and unlocking. default: true.
• Returns: {Object} A new mutex object.

Create a mutex object. first try to open the mutex object with same name. If not found, create a new object. The name parameter is valid for all tasks of the entire process. Different tasks can create semaphore objects with same name for inter-task mutual exclusion.

If prioQueue is true, multitasking waits for the same mutex to be queued by task priority. You need to operate shared resources as soon as possible. By default, no events will be generated between lock() and unlock() and timers, SigSlot, and Promise will not be executed.

# Example

var m = new Mutex("MUTEX-1");

# Mutex Object

# mutex.lock([timeout])

• timeout {Integer} Wait timeout in milliseconds. default: undefined means wait forever until mutex.lock() is successful.
• Returns: {Boolean} Locked successfully returns true, otherwise false means timed out.

Mutex lock operation, if the mutex is not locked, this function will lock and return true. If the mutex has been locked by another task, this operation will block until other tasks are unlock, if the current task already locked this mutex, the mutex supports recursive locking, this function will successfully lock and return true.

# Example

var m = new Mutex('MUTEX-1');

// Support recursive locking.
m.lock();
m.lock();
...
m.unlock();
m.unlock();

# mutex.unlock()

• Returns: {Boolean} Unlocked successfully returns true, otherwise false.

Unlock mutex, unlock succeeds if the current task has already locked, otherwise fails.

# mutex.stat()

• Returns: {Boolean} Unlocked returns true, otherwise false.

Get the current mutex state immediately, unlocked returns true, otherwise false.